SIPP

NAME

SYNOPSIS

[g]cc [flags] files -lsipp -lm [ libraries ]

DESCRIPTION

The library also provides 3-dimensional texture mapping with automatic interpolation of texture coordinates. Simple anti-aliasing can be performed through oversampling. The scene can be illuminated by an arbitrary number of lightsources. These lightsources can be of three basic types: directional, point or spotlight. Light from spotlights can cast shadows.

It is possible to create several virtual cameras, and then specify one of them to use when rendering the image.

A major feature in SIPP is the ability for a user to provide his own shading function for a surface. This makes it easy to experiment with various shading models and to do special effects. The shader controls both the color and opacity of a surface. A basic shading algorithm is provided with the library, and also a number of other, more specialized shaders.

Images can be rendered directly onto a file in the Portable Pixmap format (ppm) or, for line images, Portable Bitmap, (pbm) or, with a function defined by the user, into anything that it is capable of plotting a pixel (or drawing a line).This could, for instance, be a window in a window system or even a plotter file.

USAGE

DATA TYPES

bool

A boolean type, with values TRUE or FALSE. These constants are also defined in sipp.h.

Color

A struct with three members, red, grn and blu. Each member of the struct is a double which should be in the range [0,1].

Vector

A struct with three members, x, y and z which are all doubles.

Transf_mat

Transf_mat is a standard 4 x 4 homogenous transformation matrix. Actually it is stored as a 4 x 3 matrix to save memory, since the rightmost column is only needed in the viewing calculation.

The members of a Transf_mat should never be accessed directly, but rather through the abstract functions described in the FUNCTIONS section. See also geometric(3X).

Surface and Object

Surface and Object are both opaque types used by SIPP. A predefined Object called sipp_world is used as starting point of the rendering process. All objects that should be included in the rendering must be in the object hierarchy under sipp_world.

Surf_desc

A Surf_desc is a surface description, used by the built-in shader to store properties about a surface. The definition of Surf_desc is as follows:
typedef struct {
double  ambient;  /* Fraction of color visible in ambient light */
double  specular;  /* Fraction of colour specularly reflected */
double  c3;  /* "Shininess" 0 = shiny, 1 = dull */
Color  color;  /* Colour of the surface */
Color  opacity;  /* Opacity of the surface */
} Surf_desc;

Lightsource

This structure holds information about a lightsource. Two members in the struct, color and next are of interest to users writing their own shaders. color is of type Color and spcifies the color of the light emitted from the lightsource. next is a pointer to another Lightsource struct and points to the next defined lightsource in the scene, or NULL if there are no more lightsources.

Camera

A structure holding a virtual camera. SIPP provides a predefined Camera and a pointer to it called sipp_camera. This camera is the default viewpoint used when rendering a scene.

FUNCTIONS

The rest of this manual contains a brief description of the avaliable functions in SIPP. For a full description of how to use the functions, see User's Guide to SIPP.

Initializations

void sipp_init()

Initialize the library and set up default values.

void sipp_background(red, green, blue)

double red;
double green;
double blue;

Set the background color of the image.

void sipp_show_backfaces(flag)

bool flag;

Specify if backfacing polygons should be culled or not.

void sipp_shadows(flag, dmap_size)

bool flag;
int dmap_size;

Turn shadow casting on or off and specify size of depth maps.

Object creation

void vertex_push(x, y, z)

double x, y, z;

Push a vertex onto the internal vertex stack.

void vertex_tx_push(x, y, z, u, v, w)

double x, y, z;
double u, v, w;

Push a vertex and it's texture coordinates onto the vertex stack.

void polygon_push()

Create a polygon from the vertices on the vertex stack and push it onto the polygon stack.

Surface *surface_basic_create(ambient, red, grn, blu, specular, c3, opred, opgrn, opblu)

double ambient;
double red, grn, blu;
double specular;
double c3;
double opred, opgrn, opblu;

Create a surface from the polygons on the polygon stack. The surface will be shaded by the internal shader, basic_shader(), using the parameters as values in a Surf_desc struct.

Surface *surface_create(surf_desc, shader)

void *surf_desc;
Shader *shader;

Create a surface from the polygons on the polygon stack. The surface will be shaded by shader using the surface description surf_desc.

void surface_basic_shader(surface, ambient, red, grn, blu, specular, c3, opred, opgrn, opblu)

Surface *surface;
double  ambient;
double  red, grn, blu;
double  specular;
double  c3;
double opred, opgrn, opblu;

Set surface to be shaded by the basic shader and use the other parameters as values in the Surf_desc struct.

void surface_set_shader(surface, surf_desc, shader)

Surface *surface;
void  *surf_desc;
Shader  *shader;

Set the surface surface to be shaded with the shading function shader using the surface description surf_desc.

Object *object_create()

Create an empty object.

void object_delete(obj)

Object *obj;

Delete an object, i.e. the memory used by obj and all its subobjects and surfaces are recursively freed.

void object_add_surface(obj, surf)

Object  *obj;
Surface *surf;

Add the surface surf to the object obj.

void object_sub_surface(obj, surf)

Object  *obj;
Surface *surf;

Remove the surface surf from the object obj.

void object_add_subobj(obj, subobj)

Object *obj;
Object *subobj;

Add the subobject subobj to the object obj.

void object_add_subobj(obj, subobj)

Object *obj;
Object *subobj;

Remove the subobject subobj from the object obj.

Object *object_instance(obj)

Object *obj;

Create a new instance of a previously defined object. The lists of surfaces and subobjects in obj are not copied, only a new reference with its own transformation matrix is created.

Object *object_dup(obj)

Object *obj;

Copy recursively an object and its subobjects. The surfaces in the object tree are not copied, only new references to them are made.

Object *object_deep_dup(obj)

Object *obj;

Copy the entire tree for the object obj, including subobjects and all surfaces, polygons and vertices.

Object transformations

Transf_mat *object_get_transf(obj, matrix)

Object  *obj;
Transf_mat *matrix;

Return the transformation matrix currently stored in the object obj. If matrix is not NULL, the transformation matrix will be copied to that location and a pointer to it (identical to matrix) is returned. If matrix is NULL a new matrix will be allocated, the transformation matrix copied into it and a pointer to the new matrix is returned.

void object_set_transf(obj, matrix)

Object  *obj;
Transf_mat *matrix;

Set the transformation matrix of the object obj to matrix.

void object_clear_transf(obj)

Object  *obj;

Set the transformation matrix of the object obj to the unit matrix.

void object_rot_x(obj, ang)

Object  *obj;
double  ang;

Rotate the object obj the angle ang about the X axis. ang is expressed in radians.

void object_rot_y(obj, ang)

Object  *obj;
double  ang;

Rotate the object obj the angle ang about the Y axis. ang is expressed in radians.

void object_rot_z(obj, ang)

Object  *obj;
double  ang;

Rotate the object obj the angle ang about the Z axis. ang is expressed in radians.

void object_rot(obj, point, vec, ang)

Object *obj;
Vector *point;
Vector *vec;
double ang;

Rotate the object obj the angle ang about the line given by the point point and the vector vec. ang is expressed in radians.

void object_scale(obj, xscale, yscale, zscale)

Object *obj;
double xscale, yscale, zscale;

Scale the object obj with the scaling factors xscale,yscale and zscale in the main directions respectively.

void object_move(obj, dx, dy, dz)

Object *obj;
double dx, dy, dz;

Move (translate) the object obj dx, dy and dz in the three main directions, respectively.

void object_transform(obj, matrix)

Object  *obj;
Transf_mat *matrix;

Post multiply the matrix matrix into the transformation matrix of the object obj.

Lights

Lightsource *lightsource_create(x, y, z, red, green, blue, type)

double x, y, z;
double red, green, blue;
int type;

Create a new lightsource.The type specified in type should be either LIGHT_DIRECTION or LIGHT_POINT.

Lightsource *spotlight_create(x1, y1, z1, x2, y2, z2, opening, red, green, blue, type, shadow)

double x1, y1, z1;
double x2, y2, z2;
double opening;
double red, green, blue;
int type;
bool shadow;

Create a new spotlight. type should be either SPOT_SHARP or SPOT_SOFT.

void light_destruct(light)

Lightsource *light;

Release the memory used by a lightsource or a spotlight.

void lightsource_put(lightsrc, x, y, z);

Lightsource *lightsrc;
double x, y, z;

Specify a new position or direction to a lightsource.

void spotlight_pos(spot, x, y, z);

Lightsource *spot;
double x, y, z;

Specify a new position for a spotlight.

void spotlight_at(spot, x, y, z);

Lightsource *spot;
double x, y, z;

Specify a new point that a spotlight is pointing at.

void spotlight_opening(spot, opening);

Lightsource *spot;
double opening;

Specify a new opening angle for a spotlight.

void spotlight_shadows(spot, flag);

Lightsource *spot;
bool flag;

Turn shadow casting on or off for a spotlight.

void light_color(light, red, green, blue);

Lightsource *light;
double red, green, blue;

Change the color of the light emitted from a lightsource or a spotlight.

void light_active(light, flag);

Lightsource *light;
bool flag;

Turn a lightsource or a spotlight on or off.

double light_eval(light, position, light_vector);

Lightsource *light;
Vector *position;
Vector *light_vector;

Evaluate how much light from a lightsource or a spotlight that reaches a point and calculate a vector from the light to the light.

Cameras

Camera *camera_create()

Create a new virtual camera.

void camera_destruct(camera)

Camera *camera;

Release the memory used by a virtual camera.

void camera_position(camera, x, y, z)

Camera *camera;
double x, y, z;

Define the position of a camera.

void camera_look_at(camera, x, y, z)

Camera *camera;
double x, y, z;

Define the point a camera is looking at.

void camera_up(camera, x, y, z)

Camera *camera;
double x, y, z;

Define the up vector of the camera.

void camera_focal(camera, ratio)

Camera *camera;
double ratio;

Define the focal ratio of a camera.

camera_params(camera, x, y, z, to_x, to_y, to_z, up_x, up_y, up_z, focal_ratio)

Camera *camera;
double x, y, z;
double to_x, to_y, to_z;
double up_x, up_y, up_z;
double focal_ratio;

Set all parameters of a camera in one call.

Rendering

void render_image_file(width, height, file, mode, oversampling)

int  width, height;
FILE *file;
int  mode;
int  oversampling;

Render an image of the current scene into a file. mode should be one of PHONG, GOURAUD, FLAT or LINE.

void render_field_file(width, height, file, mode, oversampling, field)

int  width, height;
FILE *file;
int  mode;
int  oversampling;
int  field;

Render the current scene as a field (half frame) into a file. mode should be one of PHONG, GOURAUD, FLAT or LINE and field should be either ODD or EVEN.

void render_image_func(width, height, pix_func, data, mode, oversampling)

int  width, height;
void (*pix_func)();
void *data;
int  mode;
int  oversampling;

Render an image of the current scene into any device. mode should be one of PHONG, GOURAUD, FLAT or LINE.

void render_field_func(width, height, pix_func, data, mode, oversampling, field)

int  width, height;
void (*pix_func)();
void *data;
int  mode;
int  oversampling;
int  field;

Render the current scene as a field (half frame) into any device. mode should be one of PHONG, GOURAUD, FLAT or LINE and field should be either ODD or EVEN.

The basic shader

void basic_shader(world, normal, texture, view_vec, lights, surface, color, opacity)

Vector *world;
Vector *normal;
Vector *texture;
Vector *view_vec;
Lightsource *lights;
Surf_desc *surface;
Color *color;
Color *opacity;

The basic shader function that is provided with the library.

SEE ALSO

AUTHORS

Index

NAME

SYNOPSIS

DESCRIPTION

USAGE

DATA TYPES

FUNCTIONS

Initializations

Object creation

Object transformations

Lights

Cameras

Rendering

The basic shader

SEE ALSO

AUTHORS